<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Support for the Remote Interface
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot057.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc115">10.6</A>&nbsp;&nbsp;Support for the Remote Interface</H2>
<A NAME="remotesupport"></A>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> provides the following predicates to support the remote
interface:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default334"></A><B>remote_connect(?Address, ?Peer, ?InitGoal)</B><DD CLASS="dd-description"> 
Initiates a remote attachment at address Host/Port. The predicate
will wait for a remote process to establish an attachment according to the
protocol described in section&nbsp;<A HREF="embroot055.html#remoteattach">10.3</A>. If instantiated, InitGoal
is called after the connection is established to perform any user defined
initialisation on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side (this can be used for example to
define a disconnection handler that will be called when the two sides
disconnect). The predicate succeeds 
when the attachment is successfully made and the remote side returns
control to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. Peer is the name of the control
connection, and is used to identify a particular remote peer (an
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session can have several).<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default335"></A><B>remote_connect_setup(?Address, ?Peer, -Socket)</B><DD CLASS="dd-description">
<TT>remote_connect/2</TT> is implemented by calls to <TT>remote_connect_setup/3</TT> and <TT>remote_connect_accept/6</TT>. These lower
level predicates allow more flexibility in the implementation of the remote
attachment, at the cost of some increased complexity.<BR>
<BR>
The two predicates must be used together, with <TT>remote_connect_setup/3</TT>
called first. The predicate creates a socket server for remote attachment
at host Host and port Port. <TT>Socket</TT> will be instantiated to the name of
the socket server that is created. When the predicate returns, the remote process
can request the socket connection at Host/Port address (if the request is
issued before <TT>remote_connect_setup/3</TT> is called, the server would
refuse the connection). The remote process will suspend waiting for the
request to be accepted. This will happen when <TT>remote_connect_accept/6</TT>
is called.<BR>
<BR>
Splitting the attachment into two predicates enables the user to start the
remote program in between. This will allow the user to start the remote
attachment automatically by executing the remote program from within
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> with an <A HREF="../bips/kernel/opsys/exec-3.html"><B>exec/3</B></A><A NAME="@default336"></A> call. <BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default337"></A><B>remote_connect_accept(?Peer, +Socket, +TimeOut,?InitGoal,?PassTerm,-InitRes)</B><DD CLASS="dd-description">
This predicate accepts an remote attachment at the socket server Socket.
This predicate is called after a call to <TT>remote_connect_setup/3</TT>, with the same arguments for Peer
and Socket. The predicate will create the control and rpc connections
according to the protocol described in section&nbsp;<A HREF="embroot055.html#remoteattach">10.3</A> with a
remote process. <TT>Socket</TT> will be closed if the attachment is
successful. <BR>
<BR>
<TT>TimeOut</TT> specifies the amount of time (in seconds) that the predicate
will wait for a remote process to attempt a remote attachment. If no remote
attachment request is made in the specified time, the predicate will
fail. This time is also used for the time-outs on peer queue connections.
To make the predicate block indefinitely waiting for a remote
attachment, the atom <TT>block</TT> can be used for <TT>TimeOut</TT>. <BR>
<BR>
<TT>InitGoal</TT> is used to define the optional initialisation on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side when the two sides are connected. InitGoal will be called
immediately after connection, before the two sides are allowed to
interact. If no initialisation is desired, then the argument can be left
uninstantiated. The result of executing the goal is returned in <TT>InitRes</TT>, which should be initially left uninstantiated.<BR>
<BR>
<TT>PassTerm</TT> is the pass-term that is used to verify the
connection. The remote side sends a pass-term which is checked to see it is
identical to <TT>PassTerm</TT>. If not, the attachment fails.<BR>
<BR>
Unimplemented functionality error is raised if the remote protocol used by
the remote and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> sides are incompatible. This can happen if
one side is outdated (and using an outdated version of the protocol). <BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default338"></A><B>remote_disconnect(+Peer)</B><DD CLASS="dd-description">
Initiates the disconnection of the remote attachment represented by
Peer. All connections (control, ec_rpc, synchronous and asynchronous
streams) will be closed. The predicate succeeds after the clean up. In
addition, a <TT>Control</TT> event will be raised. <BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default339"></A><B>remote_yield(+Peer)</B><DD CLASS="dd-description">
Explicitly yield control to the remote side Peer. Execution on
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will be suspended until the remote side returns control to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. The predicate will succeed when remote side returns
control. The predicate will abort if the remote side initiates
disconnect. The abort will occur after the remote attachment is disconnected.
The abort can be caught to allow for more graceful exits in user
applications by wrapping the <TT>remote_yield/1</TT> in a <A HREF="../bips/kernel/control/block-3.html"><B>block/3</B></A><A NAME="@default340"></A> call.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default341"></A><B>peer_queue_create(+Name,+Peer,+Type,+Direction,+Event)</B><DD CLASS="dd-description">
Creates a peer queue from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. <TT>Name</TT> is the name for the queue,
and <TT>Peer</TT> is the peer to which the queue would be connected. <TT>Type</TT> specifies if the queue is synchronous or not (atom sync or async),
and direction is the direction of the queue (fromec, toec for synchronous
queues, it is ignored for asynchronous queues), <TT>Event</TT> is the name of
the event that will be raised on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. The user should
associate an event handler goal with Event. If no event is to be raised,
then the empty atom (<CODE>''</CODE>) should be used.<BR>
<BR>
The predicate does not provide a way to specify a handler for the queue on
the peer side. This is because it is not possible to provide a generic
way that is independent of peer's programming language.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default342"></A><B>peer_queue_close(+Name)</B><DD CLASS="dd-description"> 
Closes the peer queue Name from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. </DL>
<HR>
<A HREF="embroot057.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
